{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to PySeis.\n",
    "\n",
    "## Background\n",
    "\n",
    "I was trying to edit some SU file headers in [Seismic Unix](http://www.cwp.mines.edu/cwpcodes/).  If you've ever used [suchw](http://www.cwp.mines.edu/sututor/node57.html) you will know it is not the most intuitive module.  So I started playing around with [struct](https://docs.python.org/2/library/struct.html) in order to pull the SU file into python, and kind of fell by accident into numpy's [structured arrays](http://docs.scipy.org/doc/numpy/user/basics.rec.html).  I never looked back.\n",
    "\n",
    "If you're not familiar with structured arrays they allow you to define a [numpy data type](http://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html) with various fields.  Each field can have its own [type](https://en.wikipedia.org/wiki/Data_type) - short, long, unsigned, signed, integer, float, etc.  \n",
    "\n",
    "Put together a data type with fields that match the seismic unix 240 byte header, add the trace data as another field and all of a sudden the SU file is the exact binary representation of the numpy array in memory (assuming you've got the [endianness](https://en.wikipedia.org/wiki/Endianness) correct). Reading a seismic unix file becomes as simple as \n",
    "```python\n",
    "dataset = numpy.fromfile('dataset.su', dtype=su)\n",
    "```\n",
    "and editting headers becomes as simple as\n",
    "```python\n",
    "dataset['cdp'] = (dataset['sx'] + dataset['gx'])/2.0\n",
    "```\n",
    "Of course, this is just the tip of the iceberg.  The seismic dataset is now a numpy array, and the full suite of python tools, including numpy, scipy, pandas etc are on tap.  Consider the following example:\n",
    "```python\n",
    "import numpy as np\n",
    "data = np.fromfile('raw.su', type=su)\n",
    "data['cdp'] = (data['sx'] + data['gx'])/2.0\n",
    "cdps = np.sort(data, order['cdp', 'offset'])\n",
    "fft = np.fft.rfft(cdps)\n",
    "fft[0] = 0\n",
    "cleaned = np.fft.irfft(fft)\n",
    "cleaned.tofile('cleaned.su')\n",
    "```\n",
    "In 8 lines the SU file is imported, the header word CDP is calculated and set, the dataset is sorted into cdp/offset, has any DC bias removed in the frequency domain, and is written back to another SU file. The only thing in that code block that is not off-the-shelf python is the dtype definition, i.e. `type=su`.\n",
    "\n",
    "Like I said, I never looked back.\n",
    "\n",
    "## Direction\n",
    "\n",
    "I very quickly build up a collection of python code which could be used in conjunction with seismic unix.  PySeis (PYthonic SEISmic processing) is an attempt to integrate that code into something more cohesive.  \n",
    "\n",
    "But as I started giving a short course in seismic processing it also became a teaching tool, and I have slowly been recoding the core modules to make it easier to teach.   As such I have been making some tradeoffs, including:\n",
    "\n",
    "1. readability over performance, unless the performance is painful.\n",
    "2. heavily platform agnostic (I'm on linux, students are on windows)\n",
    "3. minimal dependencies.  The teaching lab computers do not generally have the lastest verison of python, numpy or scipy\n",
    "4. stand alone. No seismic unix\n",
    "\n",
    "Initially I was tying my dependencies to the EPD free distribution, but I have moved away from that when Canopy was released. But long term I will probably tie the dependencies to either [EPD canopy](https://www.enthought.com/products/canopy/) or [Continuum's Anaconda](https://www.continuum.io/why-anaconda). Which one will probably depend upon the IT department at the University of Queensland.\n",
    "\n",
    "Currently the goal is to include sufficient code to allow for a complete but relatively basic processing sequence, along with ipython notebooks for each process. The notebooks will hopefully become the primary teaching tool in future.\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
